搭配元件篇談的是別人寫的八個系統。安裝包裡只有一支程式是自己寫的，就是 od-bridge：它坐在主機 B 上，一邊把 Vector 篩過的事件簽章後送往主機 A，一邊每 5 秒去主機 A 拉回封鎖決策，落地到這台主機的防火牆、CrowdSec 與一份給外部防火牆抓的清單。總覽第 3 篇用一節帶過它，這一篇把它拆開來講：它的兩個迴圈、四個執行點、它在記憶體與磁碟各留了什麼、主機 A 不在的時候它怎麼辦，以及讀者排錯時最常要看的它的紀錄。 主機與位址沿用防禦節點那一套：主機 A（192.168.0.111）是 BeakPlatform，主機 B（192.168.0.112）是防禦節點。

先講結論。 od-bridge 是主機 B 與主機 A 之間唯一的一條線，兩個方向都是它。往主機 A 的方向，它是 Vector 的下游：收一筆、簽一筆、轉一筆，自己不排隊、不重試，送不出去就把失敗原樣交回 Vector，由 Vector 決定要不要重送。往主機 B 的方向，它是主機 A 的執行端：每 5 秒問一次「有沒有待執行的決策」，拿到就逐一落地，再把每個執行點的成敗回報回去。它不判斷任何事情：要不要送、送哪些，Vector 決定；要不要封、封多久，主機 A 的流程決定。它做的是「把兩邊接起來」，約一千行 Python，只用一個第三方函式庫。

另外有兩件事值得先知道。第一，它幾乎不留東西：轉送紀錄、決策紀錄、計數器全在記憶體裡，重啟歸零；磁碟上只有 CrowdSec 的機器憑證與 EDL 清單。第二，它拿到的權限不小：它跑在主機網路上，帶著改防火牆的能力，能在這台主機的 kernel 裡加減封鎖項目。這兩件事合起來決定了第六節「它不做的事」與第五節「主機 A 不通的時候」會看到的行為。

一、它是什麼

od-bridge 的 od 是 Open Defense，主機 A 上負責資安案件的那個模組的名字；bridge 就是橋。它是安裝包裡唯一自己寫的程式（Apache 2.0），Python，六個檔案加四個執行點模組，連空行與註解共 1,209 行，扣掉之後約 1,000 行。唯一的第三方相依是 aiohttp，同時當 HTTP 伺服器（收 Vector、給管理者看狀態頁）與 HTTP 用戶端（送主機 A、打 CrowdSec）。它不是一個「產品」，沒有版本號，隨安裝包一起更新。

它在本安裝包裡的樣子：

二、它接在哪裡

（圖01：od-bridge 的位置。黑色實線是主機 B 內部的呼叫，藍色虛線是事件往主機 A 的方向，紅色點線是決策從主機 A 回來的方向，灰色細線是管理者與外部防火牆的讀取。）

圖上有三件事要看。

• 兩個方向是兩個獨立的迴圈，互不等待。 左邊那條是 Vector 推過來的，od-bridge 被動接；下面那條是它自己主動去主機 A 拉的。事件送不送得出去，不影響決策拉不拉得回來，反過來也一樣。所以會出現「主機 A 收不到事件、但封鎖照常落地」或相反的組合，第五節講。
• 右邊三個落地點，它只負責「寫進去」。 nftables 那一筆是 kernel 自己在守，CrowdSec 那一筆要有 bouncer 才會擋人，EDL 那一份要有外部防火牆來抓才有作用。od-bridge 寫完就回報成功，至於「有沒有真的擋到人」，它不知道也不查。
• 主機 A 的兩個端點用的是兩套身分。 送事件用事件受理金鑰，每筆 HMAC 簽章；拉決策用執行帳號，先換一張 15 分鐘的 JWT。兩套各自有自己的限流與鎖定規則，壞起來的樣子也不同，第七節的紀錄表會分開列。

三、設定值：全在 .env

od-bridge 沒有設定檔，啟動時讀環境變數，容器用 env_file: .env 把整份 .env 餵給它。下面是它會讀的每一個，分成「開通字串帶進來的」與「安裝腳本給預設值的」兩組：

開通字串本身只是一段 base64url 編碼的 JSON，裡面是上面前三列的五個值加企業網域，由主機 A 的 od_node_pairing.py 產生。它不是什麼安全機制，只是把五個值打包成一行方便貼；拿到字串的人就等於拿到這台節點對主機 A 的兩套身分，所以示範憑證檔才設成 root 0600。

四、兩個迴圈與四個執行點

ingest：收一筆、簽一筆、轉一筆

Vector 的 bridge_intake 出口把每一筆事件 POST 到 :8500/events。od-bridge 做的事按順序是：

1. 比對 Authorization: Bearer 與 BRIDGE_INGEST_TOKEN，不符 401。比對用的是常數時間的函式，而且刻意以 bytes 比對：早期版本用字串比對，送非 ASCII 的標頭會讓它拋例外變 500 而不是 401。
2. body 必須是 JSON，且至少有 correlation_id 與 source_system 兩個欄位，否則 400。它只看這兩個，其餘欄位對不對是主機 A 的事。
3. 取現在的 Unix 秒數當時間戳，對「時間戳、換行、原始 body」算 HMAC-SHA256，放進三個標頭：X-OD-Key-Id、X-OD-Timestamp、X-OD-Signature（值是 sha256= 加十六進位）。body 一個 byte 都不改地轉送，連 Vector 送來的 JSON 空白都保留，因為簽的是原始 bytes。
4. 等主機 A 回應，最多 10 秒。回應碼與 body 原樣交回給 Vector，只有 5xx 一律改成 502；連不上（逾時、拒絕連線、DNS 失敗）也回 502，body 是 upstream_unreachable 加原因。
5. 在記憶體記一筆：時間、來源、主機 A 的回應碼（連不上記 0）、correlation_id，就是 /forwards 頁的一列；同時紀錄印一行 forwarded cid=… src=… status=…。

整個過程是同步的：Vector 的那一筆要等到主機 A 回應了才拿到結果。這是刻意的，od-bridge 沒有自己的佇列、沒有重試、沒有磁碟緩衝，「送不出去怎麼辦」整個交給 Vector。Vector 篇第四節講的記憶體排隊、隊首重試、重啟遺失，全是這個設計的結果。od-bridge 自己只是一個會簽章的轉接頭。

主機 A 那一端怎麼驗：用 X-OD-Key-Id 找金鑰，用金鑰的 secret 重算一次簽章比對，時間戳與主機 A 的時鐘差超過 5 分鐘一律拒絕（防重放），三者任一不對都回同一個 401 auth_failed，不說是哪一個。所以「主機 B 的時鐘慢了六分鐘」在 od-bridge 的紀錄裡長得和「金鑰貼錯」一模一樣，排錯時先對兩台的時間。通過認證之後，主機 A 依序查金鑰的來源範圍（403 scope_denied）、事件格式（400 validation_error）、企業有沒有對應的事件路由（422 no_mapping），都過了才建案，回 200 並在 body 標示是不是重複的 correlation_id。主機 A 另有每把金鑰每分鐘 100 筆、每小時 5,000 筆的限流，超過回 429。

executor：每 5 秒問一次，拿到就落地

第二個迴圈不等任何人，自己定時跑。一輪做的事：

實測的時序（2026 年 10 月 4 日在測試環境走的一整圈）：資安人員在主機 A 的案件上按「封鎖」，決策寫入；od-bridge 在下一次輪詢拿到，三個執行點依序落地，PATCH applied，從決策寫入到 applied 只有幾秒。主機 A 決策頁上那筆的 application_result 長這樣（三個執行點各自的回報）：

{"nftables": {"ok": true, "set": "blocklist", "element": "203.0.113.42 timeout 3600s"},
 "crowdsec": {"ok": true, "status": 201, "body": "[\"142\"]"},
 "edl":      {"ok": true, "file": "/state/edl/blocklist.txt", "block_entries": 1, "allow_entries": 0}}

接著管理員撤銷：主機 A 把原決策標成 revoked，並新產生一筆 unblock 決策，執行點與原決策相同；od-bridge 下一輪拉到，三處各自移除，回報 applied。TTL 到期也是同一套：主機 A 每分鐘的排程把過期的 applied 決策標成 expired、產生一筆 unblock。od-bridge 從不自己判斷「到期了」，解封永遠是主機 A 下的一筆新決策；它唯一自己做的到期處理是 EDL 清單的剔除（下一段）。

四個執行點

五、主機 A 不通的時候

兩個迴圈分開看。

ingest 這一邊：每筆轉送都連不上，od-bridge 立刻回 502 給 Vector，紀錄每筆印一行 forward failed 加 Cannot connect to host，/stats 的 unreachable 計數跳、/forwards 頁同一個 correlation_id 每 20 到 30 秒出現一列、狀態 0。它自己什麼都不留，排隊的是 Vector。這一段 Vector 篇第四節整節在講，不重複；要記得的只有「/forwards 頁同一筆反覆出現」是 Vector 在重試隊首，不是 od-bridge 壞了。

executor 這一邊：GET 失敗就退避，1、2、4、…、60 秒一次，紀錄每次一行 GET decisions 502 或 executor loop error。主機 A 回來之後，下一次輪詢就恢復 5 秒一次，期間累積在主機 A 的 pending 決策一次拉完（一次最多 100 筆）。沒有任何決策會因為主機 A 停機而遺失，它們本來就在主機 A 的資料表裡等。

反過來，od-bridge 自己重啟或停掉，會丟的是：/stats、/forwards、/decisions 三頁的內容（記憶體）、手上的 JWT（重啟後重登一次）。不會丟的是：kernel 裡的 blocklist（連剩餘的 timeout 都在，因為那是 kernel 的狀態，不是它的）、CrowdSec 裡的 ban、EDL 的清單與 state.json。所以「重啟 od-bridge」是安全的操作，封鎖不會因此失效或重複。安裝腳本的 --reconfigure 重建防火牆表時會先把 blocklist 的元素連同剩餘 timeout 記下來再補回去，也是同一個理由。

還有一種「不通」是認證層的：主機 A 活著，但事件一律 401。可能是開通字串貼錯、金鑰在主機 A 被停用，或兩台主機的時鐘差超過 5 分鐘。三者在 od-bridge 的紀錄裡長得一樣，都是 status=401；Vector 對 401 不重試，所以這些事件在主機 A 那邊就沒了（ClickHouse 仍有）。這是整條鏈裡少數「靜默遺失」的點，第七節的表有列。

六、它不做的事

把它停掉會怎樣：Vector 的 bridge_intake 出口連不上，回應是連線被拒而不是 502，Vector 一樣當失敗重試、隊首卡住，行為與主機 A 不通相同；主機 A 的新決策堆在 pending；已經在 kernel 裡的封鎖照常到期、CrowdSec 裡的 ban 照常到期、EDL 檔不再更新（外部防火牆抓到的是停掉當下那一份，過期的項目不會自己消失）。WAF、Suricata、ClickHouse、Grafana 全部不受影響。重新啟動後一切自己接上，不需要任何手動步驟。

七、怎麼確認它在做事

先看活著、設定對不對。第一個指令就是 install.sh --verify 裡「od-bridge /health」那一行；第二個看它啟動時印的三行，從這三行可以直接讀出它認為自己的角色是什麼：

# 主機 B
curl -s http://127.0.0.1:8500/health
{"ok": true}

cd /opt/integrated-waf
sudo docker compose logs --no-color od-bridge | grep ' main: \| ingest server'
od-bridge-1  | … INFO main: executor enabled, polling every 5.0s for points=nftables,crowdsec,edl
od-bridge-1  | … INFO main: edl enforcer enabled, dir=/state/edl prune every 60.0s
od-bridge-1  | … INFO ingest: ingest server :8500 → http://192.168.0.111:8000/beakplatform/api/open_defense/intake

看到 executor DISABLED (no SA credentials in env) 就是 SA_ID 沒帶進來，節點只會送事件。再看 /stats，四組數字各自回答一個問題：

# 主機 B（或 --admin-ips 內的瀏覽器開 http://192.168.0.112:8500/stats）
curl -s http://127.0.0.1:8500/stats | sed 's/<[^>]*>/ /g' | tr -s ' \n'
 Stats uptime 43692s · last executor iter +1s ago
 Intake (Vector → bridge → BP) 1 total 1 2xx 0 4xx 0 5xx 0 unreachable
 Executor (BP /decisions) 0 processed 0 applied 0 partial 0 failed
 SA token logins: 52 · 429: 0 · GET 401: 0 · current token valid for: 191s

要看封鎖有沒有真的落在這台主機上，看 kernel 而不是看 od-bridge。/state/nft 是 od-bridge 替你跑 nft -j list set 的結果，與直接下指令等價：

# 主機 B
curl -s http://127.0.0.1:8500/state/nft
{"blocklist": {"203.0.113.42": 3412}, "blocklist6": {}, "allowlist": ["192.168.0.50", "192.168.0.111"]}
#                              ^ 剩餘秒數，kernel 自己在倒數

sudo nft list set inet secstack blocklist
sudo docker compose exec -T crowdsec cscli decisions list       # Source 欄是 od-bridge 的就是平台下發的
curl -s http://127.0.0.1:8500/edl                                 # 一行一個，沒有別的

要走一整圈，install.sh --test-event 丟一筆攻擊者 203.0.113.42 的測試事件進 Vector，幾秒後 /forwards 多一列 status=200、主機 A 多一張案件；到案件上按「封鎖」，幾秒後 od-bridge 的紀錄印 decision … action=block target=ip/203.0.113.42 points=[…]，上面三個指令各多一筆；撤銷之後各少一筆。這條路徑在讀者文件的安裝章節有逐步寫，這裡只列它在 od-bridge 這一端的樣子。

最後是它的紀錄。正常運作時它話很少：每 14 分鐘一行登入、每筆轉送一行、每筆決策一行，其餘出現的都值得看：

od-bridge 在整體裡的位置到此說完。它是整個安裝包裡最小的一個程式，也是唯一一個「兩台主機之間」的程式：事件經它出去，決策經它回來，而它對兩者都不做判斷。讀者把這套東西拆開來改的時候，Vector 可以換成 Fluent Bit、CrowdSec 可以不裝、Grafana 可以不要，但這一千行要留著，或者照第 3 篇列的契約自己寫一支。契約只有三個端點、兩套身分、六個欄位。搭配元件篇與專篇到這裡是九篇；安裝包裡剩下的主機層腳本（tunnel 建立、網卡卸載、紀錄輪替、歡迎頁），合在最後一篇講。